DHTMLX Documentation

Headers and footers in grid

Default grid header

By default the grid is rendered with a single line header, which is defined by the following command:
    grid.setHeader
The parameter of this command is a list of values, which will be used as column labels:
    grid.setHeader("A,B,C")
or
    grid.setHeader(["A","B","C"])

The values of the header are treated as HTML, so you can put any HTML tags inside setHeader command:
    grid.setHeader("<img src='some.gif'>,B,C")
The above mentioned snippet will render the grid header with an image as a label for the first column.

The syntax of setHeader command uses a comma as a separator. So you need to escape it in a special way and then it will be processed correctly.
    grid.setHeader("A,B,C");    // => will result in three columns "A" , "B" and "C"
    grid.setHeader("A\\,B,C");    // => will result in two columns "A,B" and "C"

The align of the header labels is defined by css and is not equal to the align of data columns.
If you need to specify the different align (or any other styling for different columns), you can use the following two approaches:

a) Use the third parameter of setHeader command:
    grid.setHeader("A,B,C",null,["text-align:right;","text-align:left;","text-align:center"]);
As a result each column will have its own align settings.

b) You can use inline HTML tags to define the align:
    grid.setHeader("<div style='width:100%; text-align:left;'>A</div>,B,C");

Grid without header

Grid can be initialized in such a way that the header line will not be visible. To do so you need to have the following initializing code:
grid.setHeader("A,B,C")
grid.setNoHeader(true);
Please, take into account that you still need the setHeader command with the correct list of parameters (the grid detects the count of columns based on the values of setHeader command. So it is mandatory, even in case when we don't want any grid header).

Multiline headers | footers

attachHeader command can be used to add one more line into the header, after the first one. The syntax here is nearly the same as for setHeader command:
    grid.attachHeader("A,B,C")
or
    grid.attachHeader(["A","B","C"])

If you need to assign some custom style:
    grid.attachHeader("A,B,C",["text-align:right;","text-align:left;","text-align:center"]);

The sibling command exists to attach footers (the first and one more line):
    grid.attachFooter("A,B,C")
or
    grid.attachFooter(["A","B","C"])

If you need to assign some custom style:
    grid.attachFooter("A,B,C",["text-align:right;","text-align:left;","text-align:center"]);

Both attachHeader and attachFooter commands support the HTML as values, so they may contain any HTML compatible content.

Any footer|header line can be detached later using:
    grid.detachHeader(index)
    grid.detachFooter(index)
Where "index" is 1-based index of header|footer row, which needs to be detached. Please, take into account that the first header row can't be detached.

Accessing header values

The values of header cells can be got in the following way:
grid.getColumnLabel(c_index,r_index);

And can be set as
grid.setColumnLabel(c_index,value,r_index);

Where

c_index - 0-base index of the column;
r_index - 1-base index of the row, optional; if omitted, then the first header row will be used.

Colspans and rowspans in header

Multiline headers (footers) can have colspans and rowspans. There is no special API that calls for such task, the functionality is based on special cell values.
If the header cell contains:
    #cspan - the cell will be joined with the cell to the left of the current one;
    #rspan - the cell will be joined with the cell above the current one.

For example:
    grid.setHeader("A,#cspan,B");

A		B
data1	data2	data3

    grid.setHeader("A,#cspan,#cspan")
    grid.attachHeader("A1,B1,#cspan")
    grid.attachHeader("#rspan,B2,C2")

A
A1	B1
	B2	C2
data1	data2	data3

One and the same cell can't be included in both rowspan and colspan at the same time.

Initialization from XML

With initialization from HTML values of the first header line can be defined as a part of head/column structure. Additional lines of headers|footers can be specified using the afterInit/call@command

<rows>
    <head>
        <column ... >A</column>
        <column ... >B</column>
        <column ... >C</column>
     <afterInit>
        <call command="attachHeader"><param>A1,B1,C1</param></call>
        <call command="attachHeader"><param>A2,B2,C2</param></call>
        <call command="attachFooter"><param>AF,BF,CF</param></call>
     </afterInit>
    </head>

The same syntax is used to define colspans and rowspans working with the initialization from XML (be sure to omit whitespaces around #rspan and #cspan values).

Initialization from HTML

In case of grid initialization from HTML table the first line of the table will be treated as the header line. There is no way to define additional lines of header|footer in such case (they can be added later by JavaScript).

<table>
    <tr><td>A</td><td>B</td><td>C</td></tr>
    <tr><td>data 1</td><td>data 2</td><td>data 3</td></tr>
       ...

Initialization from CSV

In case of initialization from CSV the first line of the header can be treated as the header line. This can be enabled|disabled in the following way:
grid.enableCSVHeader(true|false);

If mode is enabled - the first line of CSV will be used as the header.
If mode is disabled - the CSV will be treated as data only (in such case the header must be defined by js API before CSV loading).